package pl.edu.szlif.mosm.commonlib.provider;

import javax.microedition.lcdui.Image;

/**
 * A interface for classes concerned with providing map tiles.
 * 
 * @author Antoni Kędracki
 */
public interface TilesProvider {

	/**
	 * Calculates the longitude given a point in tile coordinates system.
	 */
	public double calculateLon(double tx, double ty, int zoom);

	/**
	 * Calculates the Latitude given a point in tile coordinates system.
	 */
	public double calculateLat(double tx, double ty, int zoom);

	/**
	 * Calculates the x map tile coordinate given a point in geographic
	 * coordinates system.
	 */
	public double calculateTileX(double lon, double lat, int zoom);

	/**
	 * Calculates the y map tile coordinate given a point in geographic
	 * coordinates system.
	 */
	public double calculateTileY(double lon, double lat, int zoom);

	/**
	 * Returns the maximum zoom level supported by this provider.
	 * @return
	 */
	public int getMaxZoom();
	
	/**
	 * Requests a map tile with the given coordinates, and a listener.
	 * 
	 * @param tx
	 * @param ty
	 * @param listener
	 */
	public void requestTile(int tx, int ty, int zoom, TilesProviderListener listener);

	/**
	 * Returns height of single tile in pixels.
	 * @return
	 */
	public int getTileHeight();
	
	/**
	 * Returns width of single tile in pixels.
	 * @return
	 */
	public int getTileWidth();
	
	/**
	 * @author Antoni Kędracki
	 */
	public interface TilesProviderListener {
		/**
		 * Returns the tile retrieved by a request.
		 * @param tx
		 * @param ty
		 * @return
		 */
		public void tileReady(int tx, int ty, int zoom, Image tile);

		/**
		 * Informs that a tile request failed to complete.
		 * @param tx
		 * @param ty
		 */
		public void tileNotAvailable(int tx, int ty, int zoom);
	}
}
